Windows Install XML (WIX) is a nice simple way to create an MSI installation file.  Some of the items it automatically handles, such as registering with Add / Remove Programs, are very nice features.

In this example we are going to create a simple MSI that deploys a single file.

Prequisites

• This assumes you have already installed Visual Studio 2010. If not, download and install it now. http://www.microsoft.com/visualstudio/en-us.  I haven’t tried the Express edition, but it may work.
• This also assumes that you have also installed the WIX 3.5 add-ons. If not, download the latest 3.5 or 3.6 build and install both ProjectAggregator2.msi and Wix35.msi: http://wix.sourceforge.net/releases/

Step 1 – Create a WIX project in Visual Studio

Creating a new project is a very simple task once you have done it a few times.  However, I try to make my walk-thrus newbie proof, so even some one who has never done this feels comfortable. So if you need help with this step, use my instructions below.  If you don’t, skip them.

1. Open Visual Studio if it is not already open.
2. Got to File | New | Project.
3. You should have an option under Installed Templates for Windows Install XML. Select it.
4. Now you should see the option for Setup Project.  Select it.
5. Enter a Name for the project. I called the project I made for this walk-thru DeployOneFile.
6. Change the directory to store the project if you want.  It doesn’t matter what directory you choose, but it is nice to keep your learning projects organized.
7. Click OK.

Your project should now be created.  In solution explorer you should now have a solution, a project, a reference and the Product.wxs.  See the image below.

Ok, I hope that was easy for you.  Let move on.

Step 2 – Add a file to the project

These steps are preformed in Visual Studio on the project you just created in the above step.

1. Right-click on the project name, DeployOneFile, and from the drop down, choose Add | New Item.
2. Select Text File.
3. Name it whatever you want. I  used Install.conf for this example.
4. Click Add.

Your file is now added to the Visual Studio project.  However, it is not automatically added into the Product.wxs as a file to be installed. This is done manually in the next step.

Step 3 – Take a moment to learn

We are going to change the Product.wxs file to include the file we just created.

The Product.wxs file has the following XML text in it.  Take a moment to look at the XML nodes and their elements so are familiar with the syntax it is using.

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
	<Product Id="fae97512-4eca-4271-821d-75b7a8861557" Name="DeployOneFile" Language="1033" Version="1.0.0.0" Manufacturer="DeployOneFile" UpgradeCode="fec17f7b-060e-466f-8bd2-7895eb2b92ce">
		<Package InstallerVersion="200" Compressed="yes" />

		<Media Id="1" Cabinet="media1.cab" EmbedCab="yes" />

		<Directory Id="TARGETDIR" Name="SourceDir">
			<Directory Id="ProgramFilesFolder">
				<Directory Id="INSTALLLOCATION" Name="DeployOneFile">
					<!-- TODO: Remove the comments around this Component element and the ComponentRef below in order to add resources to this installer. -->
					<!-- <Component Id="ProductComponent" Guid="927a42ea-a6df-45f6-ac52-4b979194bc10"> -->
						<!-- TODO: Insert files, registry keys, and other resources here. -->
					<!-- </Component> -->
				</Directory>
			</Directory>
		</Directory>

		<Feature Id="ProductFeature" Title="DeployOneFile" Level="1">
			<!-- TODO: Remove the comments around this ComponentRef element and the Component above in order to add resources to this installer. -->
			<!-- <ComponentRef Id="ProductComponent" /> -->

			<!-- Note: The following ComponentGroupRef is required to pull in generated authoring from project references. -->
			<ComponentGroupRef Id="Product.Generated" />
		</Feature>
	</Product>
</Wix>

The text of the Xml gives us hints as to what we are supposed to do in its comments.  Take a moment and read the comments.

Step 4 – Configure the WIX Xml file to deploy that file

Lets start editing that XML file.

Note: I am going to use the term “node’ to indicate and XML section. So and everything it contains is a node. If a node is inside it, I might call it a subnode.

1. Uncomment the Component node the Directory nodes.
2. Remove the two TODO: comments.
3. Uncomment the ComponentRef node that is inside the Feature node.
4. Remove the TODO: comment and the Note comment.
5. Inside the Component node, at a File node as follows:

   <File Id='Install.conf_id' Name='Install.conf' DiskId='1' Source='Install.conf' KeyPath='yes' />
   

Ok, you are done.  Yes, that was all there is too it.

You XML syntax should now look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
  <Product Id="fae97512-4eca-4271-821d-75b7a8861557" Name="DeployOneFile" Language="1033" Version="1.0.0.0" Manufacturer="DeployOneFile" UpgradeCode="fec17f7b-060e-466f-8bd2-7895eb2b92ce">
    <Package InstallerVersion="200" Compressed="yes" />

    <Media Id="1" Cabinet="media1.cab" EmbedCab="yes" />

    <Directory Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder">
        <Directory Id="INSTALLLOCATION" Name="DeployOneFile">
          <Component Id="ProductComponent" Guid="927a42ea-a6df-45f6-ac52-4b979194bc10">
            <File Id='Install.conf_id' Name='Install.conf' DiskId='1' Source='Install.conf' KeyPath='yes' />
          </Component>
        </Directory>
      </Directory>
    </Directory>

    <Feature Id="ProductFeature" Title="DeployOneFile" Level="1">
      <ComponentRef Id="ProductComponent" />
      <ComponentGroupRef Id="Product.Generated" />
    </Feature>
  </Product>
</Wix>

Ok, you are ready to build.

Step 4 – Build the project

Well, there really isn’t much to debug, so we are only going to build a release version here.

1. In the Visual Studio 2010 tool bar, there should be a drop down box that either says Debug or Release.  Change it to Release if it is not already at Release.
2. Select Build | Build Solution or use the shortcut key.

You should now have an MSI built in the project’s bin\release directory.

Step 5 – Test the MSI

Let’s go get the MSI and test it.

1. Right-click on the project, DeployOneFile, and choose, Open Folder in Windows Explorer.
2. In Explorer, navigate into the bin\release directory.
3. You will see two files:
   DeployOneFile.msi – This is the MSI and is all you need.
   DeployOneFile.wixpdb – This is a file for debugging only. You may never use it unless you need to debug.
4. You may or may not want to test the MSI on you development box. If  you do, just double-click the MSI.  Otherwise, copy it to a test box and run the MSI there.
5. Verify that the file installed.
   Note: If on a 64 bit system, it will by default install as an x86 app, so look in c:\program files (x86)\ for a folder called DeployOneFile.
6. Check Add / Remove Programs to make sure the install shows up there and that the uninstall works.

Congratulations. You just use WIX to create and deploy your first MSI.

Bonus Information – Learning about Repair

Repairing an installation is an important feature of  to understand.

What you are going to learn here, is that if you delete a file in a component that has the KeyPath=’yes’ tag, the component will reinstall.

1. Make sure the MSI you just created above is installed. If you uninstalled it doing steps above, reinstall it.
2. On the machine where you installed the MSI, Browse to the installation directory.My directory is here.
   C:\Program Files (x86)\DeployOneFile
3. The only file in that directory is the file you installed:
   Install.conf
4. Delete the Install.conf file.
5. Still on the machine where you installed the MSI, go to Add / Remove Programs.
6. Right-click on the DeployOneFile instance and choose Repair.
7. The file you deleted should be restored.

Ok, so you probably have questions about repair.  This was just a basic introduction.  Hopefully we will learn more about repair as we go on.